.\" Hey Emacs, this is an -*- nroff -*- document
.\"
.\" Copyright (C) 2016-2019  Joachim Nilsson
.\"
.\" Permission to use, copy, modify, and/or distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\" 
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd March 8, 2020
.Dt MCJOIN 1
.Os
.Sh NAME
.Nm mcjoin
.Nd tiny multicast testing tool
.Sh SYNOPSIS
.Nm
.Op Fl dhjsv
.Op Fl c Ar COUNT
.Op Fl i Ar IFNAME
.Op Fl l Ar LEVEL
.Op Fl p Ar PORT
.Op Fl r Ar SEC
.Op Fl t Ar TTL
.Op Fl w Ar SEC
.Op Ar [SOURCE,]GROUP0 .. [SOURCE,]GROUPN | [SOURCE,]GROUP+NUM
.Sh DESCRIPTION
.Nm
can be used to join IPv4 and IPv6 multicast groups, display progress as
multicast packets are received, and also send multicast packets on
select groups.
.Pp
.Nm
can help verify intended IGMP snooping functionality in layer-2 bridges
(switches), as well as verify forwarding of multicast in static or
dynamic multicast routing setups.
.Pp
.Nm
supports source-specific multicast, SSM (S,G), as well as any-source
multicast, ASM (*,G).  The source IP of an (S,G) pair is an optional
argument that must precede the group and be separated with a comma.  No
spaces are allowed between source and group in this form.  Multiple
(S,G) pairs are separated with space.
.Sh OPTIONS
With no options given
.Nm
acts as a multicast receiver (or sink), joining the default group
225.1.2.3, listening on the default interface, eth0, binding to the
default port, 1234.
.Pp
Use the following options to adjust this behavior:
.Bl -tag -width Ds
.It Fl c Ar COUNT
Stop sending/receiving after COUNT number of packets
.It Fl d
Run as a daemon in the background, detached from the current terminal.
All output, except progress is sent to
.Xr syslog 3 .
.It Fl h
Print a summary of the options and exit
.It Fl i Ar IFNAME
Interface to use for sending/receiving multicast, default: eth0
.It Fl j
Join groups, default unless acting as sender
.It Fl l Ar LEVEL
Control
.Nm
log level; none, notice, debug.  Default: notice.
.It Fl p Ar PORT
UDP port number to send/listen to, default: 1234
.It Fl s
Act as sender, sends packets to select groups, 1/100 msec, default: no
.It Fl r Ar SEC
Do leave/join repeatedly every SEC seconds.  Should not be needed
anymore, kept for backwards compatibility.
.It Fl t Ar TTL
TTL to use when sending multicast packets, default: 1
.It Fl v
Show version information
.It Fl w Ar SEC
Initial wait, sleep
.Ar SEC
seconds before starting anything.  Useful for scripting test systems
that launch
.Nm
at boot without syncing with creation of networking.
.El
.Sh USAGE
To verify multicast connectivity, the simplest way is to run
.Nm
on one system, without arguments, and on the other with the command
option
.Ar -s .
In this setup one system joins the group
.Ar 225.1.2.3
waiting for packets to arrive, and the other end starts sending packets
to the same group.  To verify routing of multicast, make sure to add the
.Ar -t TTL
option to the sender since the default TTL is 1 and every router
(simplified) decrements the TTL.
.Pp
For a more advanced example, say you want to verify that your topology
can forward 20 consecutive groups in the MCAST_TEST_NET, as defined in
RFC5771.  Simply add the following as a standalone argument to both the
receiver and the sender:
.Ar 233.252.0.1+20
.Pp
For non-consecutive groups, simply add them in any order you want, up to
250 groups are supported:
.Ar 225.1.2.3 226.3.2.1+12 225.3.2.42 232.43.211.234
.Pp
To run
.Nm
as both a sender and a receiver on the same host you will likely need to
employ something like network namespaces (Linux netns) for at least one
of them.  Otherwise the network stack will likely let the sender's data
stream take a short cut to the receiver, without passing through an
actual wire.
.Pp
Also, like most network applications, to run properly
.Nm
needs both the loopback (lo) interface and a default route set up.  At
least in the default (receiver) case.  In a network namespace neither of
these are set up by default.
.Sh SEE ALSO
.Xr omping(1) ,
.Xr ping(1) ,
.Xr mgen(1)
.Sh BUGS
Use the project's GitHub page to file bug reports, feature requests or
patches (preferably as GitHub pull requests), or questions at
.Aq https://github.com/troglobit/mcjoin
.Sh AUTHORS
Originally written by David Stevens, currently maintained by Joachim
Nilsson at GitHub.
